home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / c / Swap.man < prev    next >
Encoding:
Text File  |  1991-06-03  |  8.3 KB  |  201 lines
  1.  
  2.  
  3.  
  4. Swap                  C Library Procedures                   Swap
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NNAAMMEE
  11.      Swap_Buffer - Do byte-swapping and alignment of data buffers
  12.      Swap_BufSize - Calculate the necessary buffer size  to  hold
  13.      swapped and aligned data
  14.  
  15. SSYYNNOOPPSSIISS
  16.      ##iinncclluuddee <<sswwaappBBuuffffeerr..hh>>
  17.  
  18.      void SSwwaapp__BBuuffffeerr(_i_n_B_u_f,  _i_n_S_i_z_e,  _i_n_T_y_p_e,  _o_u_t_T_y_p_e,  _f_o_r_m_a_t,
  19.      _o_u_t_B_u_f, _o_u_t_S_i_z_e_P_t_r)
  20.  
  21.      void SSwwaapp__BBuuffSSiizzee(_i_n_B_u_f, _i_n_S_i_z_e,  _i_n_T_y_p_e,  _o_u_t_T_y_p_e,  _f_o_r_m_a_t,
  22.      _o_u_t_S_i_z_e_P_t_r)
  23.  
  24. AARRGGUUMMEENNTTSS
  25.      char     *_i_n_B_u_f         (in)      In-coming data buffer
  26.  
  27.      int      _i_n_S_i_z_e         (in)      Size in bytes of inBuf
  28.  
  29.      int      _i_n_T_y_p_e         (in)      Type  of  byte-order   and
  30.                                        alignment of data in inBuf
  31.  
  32.      int      _o_u_t_T_y_p_e        (in)      Type  of  byte-order   and
  33.                                        alignment  of data in out-
  34.                                        Buf
  35.  
  36.      char     *_f_o_r_m_a_t        (in)      String  describing  format
  37.                                        of   data  in  inBuf  (see
  38.                                        below for more details)
  39.  
  40.      char     *_o_u_t_B_u_f        (out)     Buffer  in  which  to  put
  41.                                        out-going    swapped   and
  42.                                        aligned data
  43.  
  44.      int      *_o_u_t_S_i_z_e_P_t_r    (in/out)  outSizePtr  is  an  in/out
  45.                                        parameter              for
  46.                                        SSwwaapp__BBuuffffeerr(()), but just an
  47.                                        out      parameter     for
  48.                                        SSwwaapp__BBuuffSSiizzee(()).  See below
  49.                                        for     its     use     in
  50.                                        SSwwaapp__BBuuffffeerr(())          and
  51.                                        SSwwaapp__BBuuffSSiizzee(()).
  52.  
  53. _________________________________________________________________
  54.  
  55. DDEESSCCRRIIPPTTIIOONN
  56.      These routines are obsolete.  See Fmt instead.
  57.  
  58.      SSwwaapp__BBuuffffeerr(()) takes  a  buffer  of  data  (_i_n_B_u_f)  from  one
  59.      machine  byte-order and alignment type (_i_n_T_y_p_e) and produces
  60.      an output buffer (_o_u_t_B_u_f)  of  the  same  data  swapped  and
  61.      aligned  to  conform  to  a different machine byte-order and
  62.  
  63.  
  64.  
  65. Sprite v.1.0         Printed:  June 3, 1991                     1
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72. Swap                  C Library Procedures                   Swap
  73.  
  74.  
  75.  
  76.      alignment type (_o_u_t_T_y_p_e).  The parameter  _o_u_t_S_i_z_e_P_t_r  is  an
  77.      in/out   parameter   to   SSwwaapp__BBuuffffeerr(()).    In   a  call  to
  78.      SSwwaapp__BBuuffffeerr(()), *_o_u_t_S_i_z_e_P_t_r should contain the size in  bytes
  79.      of  the  buffer parameter _o_u_t_B_u_f.  As SSwwaapp__BBuuffffeerr(()) returns,
  80.      *_o_u_t_S_i_z_e_P_t_r contains the actual  size  of  the  swapped  and
  81.      aligned  data.  If the return value of *_o_u_t_S_i_z_e_P_t_r is larger
  82.      than its input value, then SSwwaapp__BBuuffffeerr(()) needed more  buffer
  83.      space  for the out-going data than _o_u_t_B_u_f provided.  In this
  84.      case, SSwwaapp__BBuuffffeerr(()) stops swapping the data and instead cal-
  85.      culates  the  amount  of  space in bytes that it needs.   It
  86.      returns that value in *_o_u_t_S_i_z_e_P_t_r.  If  *_o_u_t_S_i_z_e_P_t_r  returns
  87.      with  a  0 value, then an error occurred, such as the _f_o_r_m_a_t
  88.      argument contained unrecognizable characters or contained  a
  89.      '*'  character  in  a position other than the last character
  90.      (see description of format string, below), or the  sizes  of
  91.      the  _f_o_r_m_a_t string or _i_n_B_u_f weren't compatible.  In the case
  92.      of an error, if SSwwaapp__BBuuffffeerr(()) is called from a user process,
  93.      it  will  panic with an error string explaining the problem.
  94.      If called in the kernel, it will print a warning-level  sys-
  95.      tem error message and return.
  96.  
  97.      SSwwaapp__BBuuffSSiizzee(()) calculates the size required for  the  _o_u_t_B_u_f
  98.      parameter   to  SSwwaapp__BBuuffffeerr(())  given  the  same  input  data
  99.      (_i_n_B_u_f), byte-ordering types (_i_n_T_y_p_e and _o_u_t_T_y_p_e),  and  the
  100.      same data format (_f_o_r_m_a_t).  It returns this calculated value
  101.      in *_o_u_t_S_i_z_e_P_t_r.  If *outSizePtr returns with a zero, then an
  102.      error   occurred.    (See   the   errors  listed  above  for
  103.      SSwwaapp__BBuuffffeerr(()) for details.)  Different  machines  have  dif-
  104.      ferent  alignment  (and thus padding) requirements, and this
  105.      is why the size of the out-going data may be different  from
  106.      the size of the in-coming data.
  107.  
  108.      The format string (_f_o_r_m_a_t) must describe  the  configuration
  109.      of  the  data in the input buffer, _i_n_B_u_f.  The data can con-
  110.      tain bytes,  half-words  (4  bytes),  words  (8  bytes)  and
  111.      double-words (16 bytes).
  112.  
  113.      The format string describes these data types as follows:
  114.  
  115.      'b'  The character 'b' stands for a byte value (1 byte).
  116.  
  117.      'h'  The character 'h' stands for a half-word (2 bytes).
  118.  
  119.      'w'  The character 'w' stands for a word (4 bytes).
  120.  
  121.      'd'  The character 'd' stands for a double-word (8 bytes and
  122.           not yet implemented).
  123.  
  124.      '0'-'9'*
  125.           A number in ascii means that the  previous  value  type
  126.           ('b,  'h', 'w', or 'd') is repeated the given number of
  127.           times.  For instance, the string "w88" means that inBuf
  128.  
  129.  
  130.  
  131. Sprite v.1.0         Printed:  June 3, 1991                     2
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138. Swap                  C Library Procedures                   Swap
  139.  
  140.  
  141.  
  142.           contains 88 word values in a row.
  143.  
  144.      '*'  A '*' character means 1 or more occurrences of the pre-
  145.           vious  value type.  A '*' can only appear at the end of
  146.           a format string, since  otherwise  there's  no  way  to
  147.           determine  the actual number of repetitions of the pre-
  148.           vious value.
  149.  
  150.      An example format  string,  "bwwh3w5b*",  would  describe  a
  151.      buffer containing the structure
  152.  
  153.               struct  flea    {
  154.                   char    mite;
  155.                   int     spider;
  156.                   int     worm;
  157.                   short   moth;
  158.                   short   mosquito;
  159.                   short   beetle;
  160.                   int     fly[5];
  161.                   char    gnat[50];
  162.               };
  163.  
  164.      The machine byte-order and alignment types  are  defined  in
  165.      swapBuffer.h.   Their names may change since complaints have
  166.      been registered about the current names, but  currently  the
  167.      types are as follows:
  168.  
  169.      SSWWAAPP__SSUUNN__TTYYPPEE
  170.           The byte-ordering and alignment of 68020's.  Looking at
  171.           an  integer  as  if  it  were an array of 4 bytes (char
  172.           buf[4]), buf[0] contains the low byte, buf[3]  contains
  173.           the  high byte, and half-words and words are aligned to
  174.           half-word boundaries.
  175.  
  176.      SSWWAAPP__VVAAXX__TTYYPPEE
  177.           The byte-ordering and alignment of Vaxen.   Looking  at
  178.           an  integer  as  if  it  were an array of 4 bytes (char
  179.           buf[4]), buf[0] contains the high byte, buf[3] contains
  180.           the  low  byte, and half-words and words are aligned to
  181.           half-word boundaries.
  182.  
  183.      SSWWAAPP__SSPPUURR__TTYYPPEE
  184.           The byte-ordering and alignment of  the  Spur  machine.
  185.           Looking at an integer as if it were an array of 4 bytes
  186.           (char buf[4]), buf[0] contains the  high  byte,  buf[3]
  187.           contains   the  low  byte.   Half-words  are  half-word
  188.           aligned and words are word aligned.
  189.  
  190. KKEEYYWWOORRDDSS
  191.      byte-order, byte-swap, padding, alignment
  192.  
  193.  
  194.  
  195.  
  196.  
  197. Sprite v.1.0         Printed:  June 3, 1991                     3
  198.  
  199.  
  200.  
  201.